Reverse Penny Drop Verification - Initiate Payment Links API

The following document highlights the details of the Initiate Payment Links API.

API Description

Objective

The Initiate Payment Links API generates multiple Unified Payments Interface(UPI) links for the penny drop transaction.

Input	Output
[Optional] The name of the user	Multiple UPI payment links (or a QR code) to initiate a penny drop transaction by the user. The complete list of output fields is provided under the Success Response Details section.

Next Step

Retrieve the bank account information of the user and the transaction status through the Retrieve Bank Details API.

API URL

https://ind-engine.thomas.hyperverge.co/v1/reversePennyDrop

API Endpoint

reversePennyDrop

Overview

The Initiate Payment Links API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - `POST`

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the Initiate Payment Links API.

Headers

Header	Mandatory / Optional	Description	Input Format
Content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the Initiate Payment Links API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
`name`	Optional	string	The name of the user. This value can assist in an additional name match verification against the account owner's name retrieved from the Retrieve Bank Details API	Not Applicable	Not Applicable
`rpdVendor`	Conditionally optional	string	Specifies the RPD vendor to use. Accepted values: `yesBankRPD`: dynamic payment recipient names `citiBankRPD`: static/fixed recipient name for all payments Optional when used for testing; Mandatory when processing verification requests outside of testing.	One of: `yesBankRPD`, `citiBankRPD`	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Initiate Payment Links API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/reversePennyDrop' \
--header 'appid: <Enter_the_appId-Shared-by-HyperVerge>' \
--header 'appkey: <Enter_the_appKey-shared-by-HyperVerge>' \
--header 'transactionId : <Enter_the_Transaction_ID>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "<Enter_the_name>",
    "rpdVendor": "yesBankRPD/citiBankRPD" // either of the two values, as per your requirement
}'

Success Response

The following code snippet demonstrates a success response from the Initiate Payment Links API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "verificationId": "<VERIFICATION_ID>",
    "upiLink": "<UPI_LINK>",
    "gpay": "<GPAY_URL>",
    "bhim": "<BHIM_URL>",
    "paytm": "<PAYTM_URL>",
    "phonePe": "<PHONEPE_URL>",
    "cred": "<CRED_URL>",
    "amazonPay": "<AMAZON_URL>",
    "mobiKwik": "<MOBIKWIK_URL>",
    "qrCode": "<BASE64_ENCODED_QR_CODE>"
  },
  "metadata": {
    "requestId": "<REQUEST_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the Initiate Payment Links API:

Parameter	Type	Description
`status`	string	The status of the request (e.g. `success`)
`statusCode`	integer	The HTTP status code returned for the request (e.g. `200`)
`result`	object	Contains the verification ID, UPI link, app-specific payment links (gpay, bhim, paytm, phonePe, cred, amazonPay, mobiKwik), and the base64-encoded QR code
`result.verificationId`	string	Unique identifier for this verification. Use this value when calling the Retrieve Bank Details API to fetch bank account and transaction status
`result.upiLink`	string	The intent link* that enables users to select their preferred UPI application on their mobile device to complete the transaction
`result.gpay`	string	The intent link* that redirects users to the Google Pay application to complete the transaction
`result.bhim`	string	The intent link* that redirects users to the BHIM application to complete the transaction
`result.paytm`	string	The intent link* that redirects users to the Paytm application to complete the transaction
`result.phonePe`	string	The intent link* that redirects users to the PhonePe application to complete the transaction
`result.cred`	string	The intent link* that redirects users to the CRED application to complete the transaction
`result.amazonPay`	string	The intent link* that redirects users to the Amazon Pay application to complete the transaction
`result.mobiKwik`	string	The intent link* that redirects users to the MobiKwik application to complete the transaction
`result.qrCode`	string	Base64-encoded representation of the QR code for the `result.upiLink`; can be displayed for scan-to-pay
`metadata`	object	Contains request and transaction identifiers for tracing and support
`metadata.requestId`	string	Unique identifier for the request; use when contacting support or for debugging
`metadata.transactionId`	string	Unique ID for the customer journey; echoes the `transactionId` sent in the request headers

Info

*Intent link: A link that directs you to start an activity in another application. It enables seamless navigation and interaction across the applications.

Failure Responses

The following code snippets demonstrate a failure response from the Initiate Payment Links API:

Verification ID Exists
Payment Link Already Created

{
  "statusCode": 400,
  "status": "failure",
  "error": "verificationId already exists",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

{
  "statusCode": 400,
  "error": {
    "message": "Created",
    "verificationId": "",
    "referenceId": "",
    "status": "CREATED",
    "addedOn": "",
    "processedOn": ""
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Responses

The following are some error responses from the Initiate Payment Links API:

Input Validation Error
Invalid Input
Invalid Seller Identifier
Partner is Inactive

{
  "message": "Input Validation Error: does not meet minimum length of 1",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

{
  "message": "Input Validation Error: is not one of enum values: citiBankRPD,yesBankRPD",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid Seller Identifier",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

{
  "status": "failure",
  "statusCode": 400,
  "error": "Partner is inactive",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Validation Error
Rate Limit Exceeded
Internal Server Error

{
  "statusCode": 400,
  "status": "failure",
  "error": "Validation error",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

{
  "statusCode": 429,
  "status": "failure",
  "error": "Rate limit exceeded",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	verificationId already exists	The provided verification ID already exists in the system	Use a different verification ID or wait for the existing verification to expire
400	Payment Link Already Created	The API has already created the payment links for the `appId`, `appKey` and `transactionId` combination.	Use a different transactionId or retrieve the existing payment links
400	Input Validation Error: does not meet minimum length of 1	The request did not meet the minimum length requirement of 1	Ensure the input parameters meet the required validation criteria
400	Validation error	The request body or parameters failed validation	Check the request payload and ensure all required fields are present and valid
400	Partner is inactive	The partner integration for the supplied credentials is inactive. The RPD vendor integration (e.g. Yes Bank) may be suspended or inactive for a defined period.	Contact the HyperVerge team to reactivate the partner or RPD vendor integration
400	Invalid Seller Identifier	The seller identifier provided is invalid or not recognized	Verify your credentials (appId/appKey) or contact the HyperVerge Integration team
400	Input Validation Error: is not one of enum values: citiBankRPD,yesBankRPD	The `rpdVendor` value is not allowed. Only `citiBankRPD` or `yesBankRPD` are accepted.	Set `rpdVendor` to either `citiBankRPD` or `yesBankRPD`
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials.	Provide valid appId and appKey credentials in the request
429	Rate limit exceeded	You have exceeded the configured rate limit for transactions per minute.	Wait before making another request or contact the HyperVerge team to adjust rate limits
500	Internal Server Error	There was an error with HyperVerge's server	Please check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

Next Step​

API URL​

API Endpoint​

Overview​

Method - POST​

Authentication​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Failure Responses​

Error Responses​

Error Response Details​